SetKeyboardFocus

SetKeyboardFocus
Header:	Controls.h		Carbon status:	Supported

Sets the current keyboard focus to a specified control part for a window.

OSErr SetKeyboardFocus (
    WindowRef inWindow, 
    ControlRef inControl, 
    ControlFocusPart inPart
);

inWindow: A pointer to the window containing the control that is to receive keyboard focus.
inControl: A handle to the control that is to receive keyboard focus.
inPart: A part code specifying the part of a control to receive keyboard focus. To clear a control’s keyboard focus, pass kControlFocusNoPart. See “Control Focus Part Code Constants”.

function result: A result code.

DISCUSSION

A control with keyboard focus receives keyboard events. The Dialog Manager tests to see which control has keyboard focus when a keyboard event is processed and sends the event to that control. If no control has keyboard focus, the keyboard event is discarded. A control retains keyboard focus if it is hidden or deactivated.

Keyboard focus is only available if an embedding hierarchy has been established in the focusable control’s window. The default focusing order is based on the order in which controls are added to the window. For more details on embedding hierarchies, see EmbedControl.

The SetKeyboardFocus function sets the keyboard focus to a specified control part. The control to receive keyboard focus can be deactivated or invisible. This permits you to set the focus for an item in a dialog box before the dialog box is displayed.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.